<?php
/**
 * @page tutorial Tutorial
 * @{
 * This tutorial is designed to introduce you to OSA's form management system, which is the core of content management.
 * These instructions assume you are generally familiar with OSA's form framework (if not, <a href="overview.html">check it out</a>!).
 * We will be building a simple page to manage fruit (editing, listing, and deleting). But first, you will need:
 * <ul>
 *     <li>
 *         A web server with PHP >= 5.2 and MySQL >= 4
 *     </li>
 *     <li>
 *         OSA installed somewhere under your web server's document root
 *     </li>
 *     <li>
 *         A text editor (I recommend the free <a href="#" onClick="window.open('http://www.activestate.com/komodo-edit')">Komodo Edit</a>)
 *     </li>
 * </ul>
 * Let's get started!
 * <ol>
 *     <li>
 *         Edit admin/index.php and add the following lines after the &lt;/table&gt; tag (line 8):
 *         @verbatim
 <br>
 <a href="<?php print $path; ?>admin/pages/fruit.php" style="text-decoration:none;">Manage Fruit</a>@endverbatim
 *     </li>
 *     <li>
 *         Create a new file 'fruit.php' in admin/pages
 *     </li>
 *     <li>
 *         Set the path variable to let everything know where this file is in the folder hierarchy.
 *         @verbatim
 $path = "../../";@endverbatim
 *     </li>
 *     <li>
 *         Include the header and footer files so the general page layout is applied to your new page.
 *         @verbatim
require_once($path."header.php");
require_once($path."footer.php");@endverbatim
 *         Now you have a new, generic page, that should look something like the picture below. You can view this by going to admin/, logging in, and clicking the link to "Manage Fruit". If you're having problems, see the <a href="#troubleshooting">troubleshooting</a> section at the end of these instructions.
 *         <br>
 *         <img src="../documents/demo1.gif"/>
 *         <br><br>
 *         Now, on to something interesting - creating a form!
 *     </li>
 *     <li>
 *         First, you'll need to include the required files:
 *         @verbatim
require_once($path."OpenSiteAdmin/scripts/classes/Form.php");
require_once($path."OpenSiteAdmin/scripts/classes/Fieldset.php");
require_once($path."OpenSiteAdmin/scripts/classes/Field.php");
require_once($path."OpenSiteAdmin/scripts/classes/RowManager.php");@endverbatim
 *     </li>
 *     <li>
 *         Now we're ready to create the actual Form:
 *         @verbatim
$form = new Form(Form::EDIT, $path."admin/");@endverbatim
 *         All we're doing is creating a new Form to edit (as opposed to add or delete) data, which will redirect to the admin page ($path."admin/") after the form is successfully submitted and processed.
 *     </li>
 *     <li>
 *         Next, you'll need a Fieldset to go in the form:
 *         @verbatim
$fieldset = new Fieldset_Vertical($form->getFormType());@endverbatim
 *         This creates a new Fieldset_Vertical (all the fields are laid out vertically, one on top of the other), with the same type as the Form it will be in.
 *     </li>
 *     <li>
 *         Now, we need to add fields. First, add the primary key Field (conventionally called ID):
 *         @verbatim
$fieldset->addField(new Hidden("ID", "", null, true, true));@endverbatim
 *         This Field is Hidden so the user won't mess with it, must have a value, and will be shown in a list view (providing chronological sorting).
 *     </li>
 *     <li>
 *         Finally, add the remaining fields:
 *         @verbatim
$fieldset->addField(new Text("name", "Name", array("maxlength"=>30), true, true));
$fieldset->addField(new TextArea("comments", "Comments", array("rows"=>4, "cols"=>30), true, false));
$fieldset->addField(new Date("expires", "Expire Date", null, true, false));@endverbatim
 *         The fields are:
 *         <ul>
 *             <li>
 *                 A Text field for the fruit name, with a maximum length of 30 characters (the size of the database field), is required, and is displayed in a list view.
 *             </li>
 *             <li>
 *                 A TextArea to hold any comments about the fruit. The Field will have 4 rows and 30 columns. This Field is also required and will not be displayed in a list view.
 *             </li>
 *             <li>
 *                 The expiration Date for this fruit, which requires no options, is required, and will not be displayed in the list view.
 *             </li>
 *         </ul>
 *     </li>
 *     <li>
 *         Now, we'll need a RowManager to interface with the database. The RowManager is going to need the name of the primary key for the table, and the easiest way to get that is to store the primary key Field when we create it by amending that addField call to read:
 *         @verbatim
$keyField = $fieldset->addField(new Hidden("ID", "", null, true, true));@endverbatim
 *         Now, we also need the primary key for the Field we are editing, which is passed in the query string:
 *         @verbatim
$id = intval($_REQUEST["id"]);@endverbatim
 *         <b>SECURITY WARNING:</b>
 *         Make sure you include the intval() cast to avoid SQL injection attacks!
 *         <br>
 *         Now we're ready to make a RowManager:
 *         @verbatim
$row = new RowManager("fruit", $keyField->getName(), $id);@endverbatim
 *         This creates a new RowManager for the table "fruit" with the specified primary key field name for the row specified by $id.
 *     </li>
 *     <li>
 *         Now we have the RowManager, lets set everything up:
 *         @verbatim
$fieldset->addRowManager($row);
$form->addFieldset($fieldset);@endverbatim
 *     </li>
 *     <li>
 *         Finally, process the Form (don't worry, the framework knows when the Form has been submitted and it should actually do something):
 *         @verbatim
$form->process();@endverbatim
 *     </li>
 *     <li>
 *         And last, but not least, display the Form:
 *         @verbatim
$form->display();@endverbatim
 *     </li>
 * </ol>
 *
 * Congratulations, you've created an edit form! The completed code should look something like this:
 * @verbatim
$path = "../../";
require_once($path."OpenSiteAdmin/scripts/classes/Form.php");
require_once($path."OpenSiteAdmin/scripts/classes/Fieldset.php");
require_once($path."OpenSiteAdmin/scripts/classes/Field.php");
require_once($path."OpenSiteAdmin/scripts/classes/RowManager.php");

require_once($path."header.php");

$id = intval($_REQUEST["id"]);

$form = new Form(Form::EDIT, $path."admin/");
$fieldset = new Fieldset_Vertical($form->getFormType());
$keyField = $fieldset->addField(new Hidden("ID", "", null, true, true));
$fieldset->addField(new Text("name", "Name", array("maxlength"=>30), true, true));
$fieldset->addField(new TextArea("comments", "Comments", array("rows"=>4, "cols"=>30), true, false));
$fieldset->addField(new Date("expires", "Expire Date", null, true, true));

$row = new RowManager("fruit", $keyField->getName(), $id);
$fieldset->addRowManager($row);
$form->addFieldset($fieldset);
$form->process();

$form->display();

require_once($path."footer.php");@endverbatim
 * <img src="../documents/demo2.gif"/>
 * <br/>
 * If you look at this, you might notice that you will forever be editing the banana (or whatever you change it to. One single fruit anyway). Perhaps a list view would be more helpful?
 * <ol>
 *     <li>
 *         First, we'll need to include the ListManager:
 *         @verbatim
require_once($path."OpenSiteAdmin/scripts/classes/ListManager.php");@endverbatim
 *     </li>
 *     <li>
 *         Now, the list will need one more Field in addition to the key Field. This Field, called the "link field", is the Field in the list that users will click on to modify that individual row. I recommend the name field, so go ahead and modify that line:
 *         @verbatim
$linkField = $fieldset->addField(new Text("name", "Name", array("maxlength"=>30), true, true));@endverbatim
 *     </li>
 *     <li>
 *         Now, change the call to $form->display() to the following block of code:
 *         @verbatim
if(empty($_GET["id"])) {
    $list = new ListManager(false);
    $list->display($fieldset, $keyField, $linkField, $_SERVER["QUERY_STRING"]);
} else {
    $form->display();
}@endverbatim
 *         This creates a new ListManager which will not span the entire width of the screen (hence the false). This ListManager will display data for our Fieldset with the given key Field, link Field, and "query string". Providing the query string just helps the list keep track of any extra parameters in the URL that you might be keeping track of, such as the session ID for users that don't support cookies.
 *         if(empty(...)) makes sure that the list is only displayed when the user hasn't selected anything. Otherwise, the Form is displayed.
 *     </li>
 * </ol>
 *
 * So now your code might look something like this. See how easy lists are? :)
 * @verbatim
$path = "../../";
require_once($path."OpenSiteAdmin/scripts/classes/Form.php");
require_once($path."OpenSiteAdmin/scripts/classes/Fieldset.php");
require_once($path."OpenSiteAdmin/scripts/classes/Field.php");
require_once($path."OpenSiteAdmin/scripts/classes/RowManager.php");
require_once($path."OpenSiteAdmin/scripts/classes/ListManager.php");

require_once($path."header.php");

$id = intval($_REQUEST["id"]);

$form = new Form(Form::EDIT, $path."admin/");
$fieldset = new Fieldset_Vertical($form->getFormType());
$keyField = $fieldset->addField(new Hidden("ID", "", null, true, true));
$fieldset->addField(new Text("name", "Name", array("maxlength"=>30), true, true));
$fieldset->addField(new TextArea("comments", "Comments", array("rows"=>4, "cols"=>30), true, false));
$fieldset->addField(new Date("expires", "Expire Date", null, true, true));

$row = new RowManager("fruit", $keyField->getName(), $id);
$fieldset->addRowManager($row);
$form->addFieldset($fieldset);
$form->process();

if(empty($_GET["id"])) {
    $list = new ListManager(false);
    $list->display($fieldset, $keyField, $linkField, $_SERVER["QUERY_STRING"]);
} else {
    $form->display();
}

require_once($path."footer.php");@endverbatim
 * <img src="../documents/demo3.gif"/>
 * <br/>
 * You may have noticed at this point that this page doesn't perform any security checking. You should always add security checking for content management pages!
 * <ol>
 *     <li>
 *         Include the SecurityManager:
 *         @verbatim
require_once($path."OpenSiteAdmin/scripts/classes/SecurityManager.php");@endverbatim
 *     </li>
 *     <li>
 *         And now, simply create a new SecurityManager for the current page:
 *         @verbatim
$securityManager = new SecurityManager("manageFruit");@endverbatim
 *         The access level has already been configured for you, but you can modify it from the editAccess link on the admin page.
 *     </li>
 * </ol>
 *
 * And now, you have a secure page to list and edit fruit!
 * <br><br>
 * But, suppose you also wanted to be able to delete fruit. Normally, it's a good idea to have a separate page for every operation, like user and access management do. But, suppose you wanted to do it on the same page. Conveniently, we can reuse much of the work we've already done:
 * <ol>
 *     <li>
 *         Create a new Form and Fieldset:
 *         @verbatim
$deleteForm = new Form(Form::DELETE);
$deleteFieldset = new Fieldset_Vertical($deleteForm->getFormType());@endverbatim
 *     </li>
 *     <li>
 *         The delete Form will just need the primary key Field for this table, so go ahead and reuse the one we created earlier:
 *         @verbatim
$deleteFieldset->addField($keyField);@endverbatim
 *     </li>
 *     <li>
 *         Now, set up the all the Form elements just like we did before, reusing the existing RowManager:
 *         @verbatim
$deleteFieldset->addRowManager($row);
$deleteForm->addFieldset($deleteFieldset);
$deleteForm->process();@endverbatim
 *     </li>
 *     <li>
 *         Finally, display the new delete Form below the edit one:
 *         @verbatim
$form->display();
$deleteForm->display();@endverbatim
 *     </li>
 * </ol>
 * And so, with almost no extra work, you can delete fruit from the same page!
 * <br><br>
 * One final trick - changing the text of the submit button. Maybe "Delete Entry" isn't quite what you were looking for. Perhaps "Throw Away"?
 * <ol>
 *     <li>
 *         Simply add this line at some point after you've created the delete Form:
 *         @verbatim
$deleteForm->setSubmitText("Throw Away");@endverbatim
 *     </li>
 * </ol>
 *
 * The final result should look something like this:
 * @verbatim
$path = "../../";
require_once($path."OpenSiteAdmin/scripts/classes/SecurityManager.php");
require_once($path."OpenSiteAdmin/scripts/classes/Form.php");
require_once($path."OpenSiteAdmin/scripts/classes/Fieldset.php");
require_once($path."OpenSiteAdmin/scripts/classes/Field.php");
require_once($path."OpenSiteAdmin/scripts/classes/RowManager.php");
require_once($path."OpenSiteAdmin/scripts/classes/ListManager.php");

require_once($path."header.php");

$id = intval($_REQUEST["id"]);
$securityManager = new SecurityManager("manageFruit");

$form = new Form(Form::EDIT, $path."admin/");
$fieldset = new Fieldset_Vertical($form->getFormType());
$keyField = $fieldset->addField(new Hidden("ID", "", null, true, true));
$fieldset->addField(new Text("name", "Name", array("maxlength"=>30), true, true));
$fieldset->addField(new TextArea("comments", "Comments", array("rows"=>4, "cols"=>30), true, false));
$fieldset->addField(new Date("expires", "Expire Date", null, true, true));

$row = new RowManager("fruit", $keyField->getName(), $id);
$fieldset->addRowManager($row);
$form->addFieldset($fieldset);
$form->process();

$deleteForm = new Form(Form::DELETE);
$deleteFieldset = new Fieldset_Vertical($deleteForm->getFormType());
$deleteFieldset->addField($keyField);
$deleteFieldset->addRowManager($row);
$deleteForm->addFieldset($deleteFieldset);
$deleteForm->setSubmitText("Throw Away");
$deleteForm->process();

if(empty($_GET["id"])) {
    $list = new ListManager(false);
    $list->display($fieldset, $keyField, $linkField, $_SERVER["QUERY_STRING"]);
} else {
    $form->display();
    $deleteForm->display();
}

require_once($path."footer.php");@endverbatim
 * <img src="../documents/demo4.gif"/>
 * <br/>
 * Now you should be able to make cool forms and lists to manage all your data!
 * Take a look at admin/pages/pageTemplate.tpl for another example of this form process, and admin/pages/multiPageTemplate.tpl for an example with multiple fieldsets working with different tables (this also demonstrates the Fieldset_Horizontal).
 * Also, check out the complete API documentation for all the cool ways you can use OSA to manage your website!
 *
 * <h2><a name="troubleshooting">
 * Troubleshooting
 * </a></h2>
 * <ul>
 *     <li>
 *          <b>If you can't log in...</b>
 *          <br>
 *          Make sure the adminstrator account has not been suspended. The "active" flag in the "users" table needs to be set to '1'.
 *     </li>
 *     <li>
 *          <b>If things randomly aren't working...</b>
 *          <br>
 *          Check the output of OpenSiteAdmin/scripts/php.php and make sure that you are using PHP 5.2 or greater. Also, make sure that the MySQL extension is installed properly.
 *     </li>
 *     <li>
 *          <b>If you can log in, but you can't stay logged in...</b>
 *          <br>
 *          Make sure you have cookies enabled.
 *     </li>
 * </ul>
 * @}
 */
?>